import argparse  # 导入命令行参数解析模块

# 创建参数解析器，描述信息为“基于PyTorch实现的项目”
parser = argparse.ArgumentParser(description="A project implemented in pyTorch")

# =========================== Learning Configs ============================
# =========================== 学习配置（模型训练核心参数）============================
# 训练的总轮数（epoch），控制模型训练的迭代总次数
parser.add_argument('--n_epoch', type=int, help='Total number of training epochs')
# 训练时的批次大小（支持短选项 -b），影响模型训练的内存占用和收敛速度
parser.add_argument('-b', '--batch_size', type=int, help='Batch size for training')
# 测试/验证时的批次大小，通常可与训练批次不同（如测试时用更大批次提高效率）
parser.add_argument('--test_batch_size', type=int, help='Batch size for testing/validation')
# 学习率，优化器更新参数的步长，是影响训练效果的关键超参数
parser.add_argument('--lr', type=float, help='Learning rate for optimizer')
# 指定使用的GPU设备（如"0"表示单卡，"0,1"表示多卡），为空则使用CPU
parser.add_argument('--gpu', type=str, help='GPU device indices (e.g., "0" or "0,1")')
# 模型快照（保存文件）的前缀路径，用于指定模型保存的目录和文件名前缀
parser.add_argument('--snapshot_pref', type=str, help='Prefix path for saving model snapshots')
# 断点续训的模型路径，若不为空则从该路径加载模型参数继续训练
parser.add_argument('--resume', type=str, default="", help='Path to resume training from a saved model')
# 仅评估模式（不进行训练），用于加载已训练模型并在测试集上评估性能
parser.add_argument('--evaluate', action='store_true', help='Only evaluate model on test set without training')
# 梯度裁剪阈值，用于解决梯度爆炸问题，将梯度 norm 限制在该阈值内
parser.add_argument('--clip_gradient', type=float, help='Threshold for gradient clipping to prevent explosion')
# 损失函数各部分的权重（若为多任务损失，用于平衡不同任务的损失占比）
parser.add_argument('--loss_weights', type=float, help='Weight for loss components (for multi-task loss)')
# 起始训练的轮数（用于断点续训，从指定epoch开始，而非从头训练）
parser.add_argument('--start_epoch', type=int, help='Starting epoch number (for resuming training)')
# 权重衰减系数（L2正则化），用于抑制过拟合，默认说明为5e-4（需在代码中显式设置默认值更合理）
parser.add_argument('--weight_decay', '--wd', type=float,metavar='W', help='Weight decay (L2 penalty), default: 5e-4')

# =========================== Display Configs ============================
# =========================== 显示配置（训练过程监控参数）============================
# 日志打印频率（每多少个batch打印一次训练信息，如损失、学习率等）
parser.add_argument('--print_freq', type=int, help='Frequency (in batches) to print training logs')
# 模型保存频率（每多少个epoch保存一次模型快照，用于备份中间结果）
parser.add_argument('--save_freq', type=int, help='Frequency (in epochs) to save model snapshots')
# 评估频率（每多少个epoch在验证集上评估一次模型性能，用于监控过拟合）
parser.add_argument('--eval_freq', type=int, help='Frequency (in epochs) to evaluate model on validation set')



